home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Software Vault: The Gold Collection
/
Software Vault - The Gold Collection (American Databankers) (1993).ISO
/
cdr23
/
chansw53.zip
/
CHAINSAW.DOC
< prev
next >
Wrap
Text File
|
1993-05-24
|
35KB
|
925 lines
CHAINSAW
A command line driven directory pruner
Public Domain, 5/24/93, Ted Davis
Version 5.3
CHAINSAW: overview
CHAINSAW is a command line driven directory pruner. It does
not stop for user confirmation and can, therefore, readily
be used from batch files. It can generate comprehensive
reports of its actions.
It provides optional password protection to prevent
casual prowlers from using it to accidentally (or
intentionally) trash a disk or directory.
CHAINSAW is a cleaning tool, useful for a variety of
tasks from cleaning out the \temp directory of files,
subdirectories, or both, to completely wiping an entire disk
during reconfiguration for a new user. This program is
potentially destructive (as is FORMAT) and is intentionally
somewhat difficult to use in its most destructive modes. It
is intended mostly for technicians, system administrators,
and power users. It is NOT intended for novice users, who
are advised to leave it strictly alone.
The command line contains the complete path,
including drive, to the directory node at which the pruning
is to occur, a password (optional) and control switches
(also optional). Switches are provided to allow the program
to delete the files in the starting directory, and to remove
that directory, as well as all the subdirectories and their
contents, or just the subdirectories. Other switches enable
operation on the root directory or network drives. Another
group of switches control which of the program's messages
will be written and whether they go to STDOUT or STDERR.
Still other switches, used with a somewhat different syntax,
allow changing the password and default switches.
CHAINSAW is FREEWARE, placed in the public domain
5/24/93 by the author, Ted Davis: it comes with absolutely
no warranty and the user's only recourse is refund of the
purchase price, which is nothing. If you use this program,
you do so on your own responsibility. If you don't want to
do that, erase your copy of the program RIGHT NOW.
There is no formal support for the program, but you
do get the source code. The author is not in a position to
provide support, but comments are welcome, as are
suggestions for improvements. Since addresses and phone
numbers tend to change, but CompuServe ID numbers are
forever, I prefer to be contacted via CIS E-mail at
73500,2314 (but do not expect a quick reply). If you find
this program useful, please let me know how you are using
it, what features you use (and never use), etc. I know how
I use it and how my beta testers use it, but the program has
a lot more in it that we routinely use.
-1-
CHAINSAW: syntax, switches
SYNTAX (most cases):
CHAINSAW {drive:path} {password} [switches] <Enter>
SYNTAX for changing default switches or password:
CHAINSAW {switch and new data} {password} <Enter>
(No matter what, the password must be the second item in the
command tail, unless suppressed.)
The default password can be found elsewhere in this manual.
The program responds to Ctrl + C and Ctrl + Break by
aborting with an ERRORLEVEL of 3 and a warning that some
damage may have been done to the given directory branch.
------------------------------------------------------------
SWITCHES, general:
Switches are introduced by a '/' or '-' character and
everything in the tail following the marker (except as noted
above) is considered a switch character or delimiter. The
acceptable delimiters are '/', '-', ',', ';', space, and tab.
Incorrect or stray characters in the command tail cause the
program to bomb with an "if you don't know what you are
doing, don't do it" message.
In the following sections, the default switches are
marked with an '*'.
Switches are processed in the order encountered,
defaults first, then those from the command tail, which can,
therefore, override the defaults.
SWITCHES, permission:
These enable or disable operations and locations.
f Enables deletion of files in the starting directory.
It is used to completely clean out a directory rather
than just empty and remove its subdirectories.
F * Disables deletion of files in the starting directory.
It is used to empty and remove the subdirectories of
the starting directory while leaving the files in
that directory intact.
g Enables removal of the starting directory as well as
all its contents, files as well as subdirectories.
G * Disables removal of the starting directory; only its
subdirectories, and, optionally, files will be
deleted.
-2-
CHAINSAW: switches
n Enables operations on network drives.
N * Disables operations on network drives.
p Enables deletion of read-only, hidden, and system
files in all permitted directories.
P * Disables deletion of read-only, hidden, and system
files in all directories.
r Enables operations in, but not on, the root
directory, if it is the starting path.
R * Disables operations in the root directory.
SWITCHES, message control
?, h, or H
Invokes the help screen, which is a VERY brief
syntax and partial switch reminder. No password is
needed with this switch.
b All messages are written to STDOUT, which can be
redirected to a file or device.
B * Directs messages to their default destinations:
Fatal error messages to STDERR
Non-fatal error messages to STDOUT
Informational messages to STDOUT
File and directory deletion messages are not printed.
d Enables directory removal listing to STDERR.
D Enables directory removal listing to STDOUT.
e Directs all messages to STDERR (the screen), which
cannot be redirected.
E Same as B.
l Enables listing of deleted files to STDERR.
L Enables listing of deleted files to STDOUT.
m Directs all fatal and non-fatal error messages to
STDERR without affecting informational and deletion
messages.
M Directs error messages to their default destinations.
-3-
CHAINSAW: switches
o Directs all fatal and non-fatal error messages to
STDOUT without affecting informational and deletion
messages.
O Same as M.
s * Enables printing of a summary at termination.
S Disables printing of the summary.
w * Turns the message output routine on. This is needed
only if the default has been changed to W.
W Turns the message output routine off. It is used in
batch files instead of sending all the messages to
STDOUT and redirecting it to NUL.
x Turns off file deletion failure messages.
X Turns off directory removal failure messages.
SWITCHES, default changing:
For all of these, except 'A', the new data string follows
the switch character without any delimiter. If a password
is needed, it must follow the switch string and be separated
from it by at least one space. The switch and string should
be the first command tail argument, the password, the
second. No more than one of these switches can be used at a
time; the program terminates after processing the first one,
without even looking to see if there are more (well, almost
like that, it will process 'a' or 'A' even if the first
switch is 'z' or 'Z'). Although the default changing syntax
given above is the preferred form, it is possible to include
these switches in a normal command tail, but it is a waste
of effort since all that happens is the default change; the
program will not change defaults AND prune the directory on
the same pass. Note: these write to the executable file,
but they still work if you rename the working copy of the
program.
a Change default switch settings. The string that
follows the 'a' must be a legal switch string, it may
contain '/' or '-' characters, but must not contain
delimiters, unless the string is quoted. Anything
that would cause the string to be passed as more than
one argument will cause an error (bad password).
A Resets the original default switches, the ones marked
with '*' in the preceding sections.
-4-
CHAINSAW: switches
z Changes the password to the string following the 'z'.
The next argument must be the existing password, if
any. This switch removes the password if the 'z' is
followed immediately by a space. Lower case 'z'
clears the screen to remove the passwords from view.
Z Exactly like 'z' except that upper case 'Z' does not
clear the screen.
------------------------------------------------------------
MESSAGES, general:
On invocation, the program displays a copyright message to
STDOUT (unless the default is changed or overridden). On
exit it displays a summary, the number of files deleted and
of directories removed to STDOUT (unless...). In between,
it may or may not display some other message or list.
The messages texts are listed in alphabetical order
within categories. Variable text is indicated by <type>.
The messages are not necessarily in exactly the same format
as they are on the screen since the screen is assumed to be
80 columns and this text file is 60 columns wide.
Note that file and directory removal list messages
both begin with "... " and removal failure messages begin
with "*** ". This allows easy separation and sorting of the
message stream with various utility programs.
The rather large number of switches controlling
message destinations are to allow generation of report files
with user determined contents. A typical case would send
the list of file deletions to redirected STDOUT, suppress
directory deletion listing, and send everything else to the
screen (STDERR); another would send the error messages to
the file, information messages to the screen and suppress
the deletion messages. In some batch file applications, any
message would be useless and all display could be
suppressed.
-5-
CHAINSAW: messages
MESSAGES, informational:
... Deleted file: <filespec>.
Indicates that the named file was successfully
deleted. This message must be specifically enabled
with the 'l' or 'L' switch. It is invoked when the C
function 'unlink' succeeds.
... Removed directory: <path>.
Indicates that the named directory was successfully
removed. This message must be specifically enabled
with the 'd' or 'D' switch. It is invoked when the C
function 'rmdir' succeeds.
CHAINSAW <version> deletes, without prompts, entire
branches of a directory tree.
Syntax: CHAINSAW {path to base directory} {password}
{switches} or CHAINSAW <modification switch> <password> (The
drive letter is required, trailing '\' is optional.
Switches may be in /bde, /b/d/e, /b /d /e, /b,/d,/e, -bde, -
b-d-e, -b -d -e, etc. format, so long as the first one
immediately follows a '/' or '-'.)
There are too many switches to define all of them here,
but... /A restores default switches, /a changes them;
b,B,d,D,e,E,l,L,m,M,o,O,s,S, w,and W control the way the
program writes its messages (and what messages it writes).
For the rest of the listed switches, lower case enables and
upper case disables the feature: f,F - file deletion in the
base directory; g,G - base directory removal; n,N -
operation on network drives; p,P - deletion of read-only,
hidden and system files; r,R - operation on the root
directory; See CHAINSAW.DOC for details."
The help screen is invoked by a '?', 'h', or 'H'
switch.
CHAINSAW aborted by user!
Directory <base path> and its subdirectories are probably
damaged.
Occurs when the user presses Ctrl + Break or
Ctrl + C.
Chainsaw deleted <number or "no"> file<s> and removed
<number or "no"> directories.
This is the summary message displayed at the end of
the program. Its presence is controlled by the 's'
and 'S' switches.
-6-
CHAINSAW: messages
CHAINSAW...New password installed.
This is the success message from the 'z' and 'Z'
switches. It indicates that no errors occurred
during the process of encrypting the new password and
writing the result to CHAINSAW.EXE.
CHAINSAW Version <version> is FREEWARE, Copyright 1992, Ted
Davis.
This is the copyright message displayed when the
program is invoked. The 'w' and 'W' switches
control its presence.
New default switches installed.
This is the success message from the 'a' switch. It
indicates that there were no errors during the
process of writing the new switch string to
CHAINSAW.EXE. It does not mean that the switch
string makes sense or will work.
Original default switches reinstalled.
This is the success message from the 'A' switch and
means that the original list of default switches has
been written to CHAINSAW.EXE.
MESSAGES, error:
Let us hope that you see few or none of these (but you
will). Some of these are followed by the appropriate DOS
error message which can be used to help determine the cause
of the error (maybe, if you have enough DOS interrupt
reference material and the message is meaningful).
*** Deletion of file: <filespec> failed.
'unlink' failed to execute properly. The reason is
likely to be obscure, perhaps a DOS error, the
drive is not erasable or the disk is write protected,
or the file is locked by another program on the
network.
*** Deletion of file: <filespec> failed. Error: read-only,
hidden, or system.
The file attributes included one or more of those
requiring special permission from the user for
deletion. The 'p' switch enables their deletion and
prevents this message, except on write protected or
read-only drives.
*** ERROR: <message>.
This follows another message and provides what the
makers of DOS and of Turbo C++ think of as helpful
explanations of a DOS interrupt function failure.
These messages are often useless, misleading, and/or
cryptic but may be helpful to DOS experts and power
users.
-7-
CHAINSAW: messages
*** Removal of directory: <path> failed.
'rmdir' failed to execute properly. The most likely
reason is that the directory, or one of its
subdirectories is not empty, perhaps due to hidden,
read-only, or system files that were not erased
because you did not use the 'p' switch or an erasure
failure.
DOS 3.0 or later is required.
This message is self explanatory; the only cure is to
upgrade your version of DOS, which you probably
should have done anyway when DOS 5.0 came out.
Memory allocation ERROR, CHAINSAW aborted.
This means either that the directory tree has too
many subdirectories on the branch in work or that a
DOS memory allocation error occurred. CHAINSAW
creates (and allocates memory for) a new instance of
the 'dirkiller' object for the base directory and for
each level of subdirectories within it. This message
occurs when the 'new' operator fails.
Password incorrect of file read error... CHAINSAW aborted.
The most usual causes are a typo in the password and
omission of all or part of the command tail. It can
also occur if CHAINSAW.EXE becomes corrupted or
cannot find itself.
Unable to change password.
This means that there was an error writing the new
password to CHAINSAW.EXE, or in finding the existing
one in the file. Make sure that CHAINSAW.EXE is not
marked read-only, that the disk is not write
protected, and if on a network, that you have write
permission for the directory in which it resides. If
none of that helps, it will be necessary to start
over with an unmodified copy of the program as
distributed.
Unable to change switches.
This means that there was an error writing the new
switches to CHAINSAW.EXE, or in finding the existing
ones in the file. Make sure that CHAINSAW.EXE is not
marked read-only, that the disk is not write
protected, and if on a network, that you have write
permission for the directory in which it resides. If
none of that helps, it will be necessary to start
over with an unmodified copy of the program as
distributed.
-8-
CHAINSAW: messages
The calling syntax for CHAINSAW was incorrect...
If you do not FULLY understand the syntax and what the
program does you should not attempt to use it. This program
DESTROYS ENTIRE BRANCHES OF THE DIRECTORY TREE.
If used incorrectly, it can do untold damage.
This is the barf message: there was something on, or
missing from, the command line that the parser did
not like. Its primary purpose is to discourage
browsers while protecting your hard disk(s). In
practice, you will get it most often by forgetting
to include the entire command tail when invoking the
program: CHAINSAW <Enter> will get it for you. The
absolute minimum command tail contains the complete
path, including drive, to the starting directory, and
unless you have turned off the password feature, the
password.
-9-
CHAINSAW: ERRORLEVELS, SAFETY
ERRORLEVELS:
CHAINSAW returns an exit code which can be read and acted
upon by a calling batch file with the IF ERRORLEVEL test.
ERRORLEVEL == 0 - Normal termination: everything went
OK, no problems.
ERRORLEVEL == 1 - aborted due to some internal error
or command tail syntax error.
ERRORLEVEL == 2 - ran to completion, but failed to
delete one or more files or
directories.
ERRORLEVEL == 3 - user aborted with Ctrl + Break or
Ctrl + C.
ERRORLEVEL == 4 - HELP message was displayed.
ERRORLEVEL == 5 - Password or default switches
changed, message indicates success
or failure.
------------------------------------------------------------
SAFETY and SECURITY:
Most directory pruners either stop and demand confirmation
from the operator before deleting anything (some prompt for
everything) or are quick knock-offs that should never leave
the authors hands. CHAINSAW is neither. It is thoroughly
thought out and tested, and while it does not prompt for
confirmation, it does have password protection to prevent
unauthorized use and a rather elaborate set of switches to
either protect or unprotect such critical areas as the root
directory; read-only, hidden, and system files; and network
drives. For those (such as the target user) who are
determined to make it easy for casual browsers to trash
their hard disks, the password feature can be turned off, if
you have the password. NOTE: the default password is
"password" (lower case, no quote marks). I buried that here
so that the potential user must at least scan the manual
before using the program.
For those users who are concerned about viruses:
when released, the program was clean, and CIS has a very
good reputation for virus free software. Nevertheless,
the best possible protection is to read, understand, and
recompile the source code. It was written using Turbo C++
PRO (the PRO is important because the inline assembly
requires TASM and TASM2MSG, which are included in the
package) with the small memory model. The only problems to
be expected with other C++ compilers would be with library
function names and the inline assembly code. Most compilers
have equivalent functions and many have some way to deal
with inline assembly. In case yours doesn't, you are on
your own. Versions after Beta 5.2 were compiled with
Borland C++ for DOS.
-10-
CHAINSAW: more about
More about CHAINSAW:
Most of the code is pure C, but the real business of the
program, recursion through the directory tree, file
deletion, and directory removal uses a C++ class named
'dirkiller' which consists of a data block and a
constructor. Construction of the object performs its work.
When the active instance of dirkiller encounters a
subdirectory, it creates a new instance of itself to process
it. Each instance is destroyed (and removed from memory)
when it finishes. This is not true recursion, it is in many
ways better. The network drive test is implemented mostly
in assembly, and is built around DOS interrupt 0x21,
function 0x44, subfunction 0x09 which reports whether a
given drive is local or remote. The source code is heavily
commented, except for the password changing and reading
functions.
The program uses the small memory model, which
accounts for some of the apparently unneeded code that
processes the command tail arguments. They seem to be
represented by far pointers and cannot be passed to
functions without a lot of trouble, or a different, and
slower, memory model.
This program grew out of a co-worker's need for a
program to remove a bunch of subdirectories created by a
batch file. It needed to work from the batch file without
operator intervention. After a bit of research and a lot of
thinking about the problem, I decided to write a generalized
command line pruner for public distribution as freeware.
Obviously, that requires both more features and at least
some protection from accidental disk trashing. It grew, and
grew, and grew. There are several more features that I
would like to add, such as a switch to allow exclusion of
specified sub-branches of the target directory, and another
to exclude, as non-overrideable defaults, specified
directories and branches (such as C:\ and C:\DOS); but I had
to draw the line somewhere. If there is a demand for them,
I will produce a version with those, and/or other, features.
If you want something really customized, I am willing to
talk money.
T.E.D. 1/11/92
-11-
CHAINSAW: more about
Addenda 3/4/93 and 5/24/93
This program has been in almost daily use by a PC support
group (over 50 PCs) for over a year. Most of the bugs
have been exterminated and usage patterns have formed and
have been analyzed. There has been only one change to the
dirkiller object in over six months, and it was rather minor
(to handle the special case of removing an already empty
directory (why anyone would use CHAINSAW instead of
RD for that completely escapes me)).
The uses of the program fall into a few distinct
classes:
1) A password protected copy in the network
search path is used mostly to strip out old
installations of user software before
upgrade or reinstallation and to clean out
user's c:\temp directories that get filled
up with batch files left by DOSSHELL when
the user reboots without dropping the
program. I took over a hundred out of one
professor's \temp directory. CHAINSAW is
preferred because it cleans out the
directory completely, including removal of
subdirectories, which DEL *.*, with its
annoying "Are you sure" prompt doesn't do.
2) Unprotected copies in the technicians'
individual paths (ahead of the global copy)
are used frequently for the original purpose
of the program: to clean up after shuffling
files through a \temp directory.
3) We use the same unprotected copies to delete
dead directories and unwanted program
installations, as after testing a new
program.
4) An unprotected copy on the same floppy as a
batch file is used to remove everything
except authorized files from lab and student
machines. The batch file marks the allowed
files as read-only and CHAINSAW is not
allowed to delete them. It also writes a
report of what it removed and did not remove
to STDOUT which is redirected to a data file
on the floppy. The DOS FIND service then
separates the removals and non-removals into
separate files for analysis. The batch file
also cleans up after itself by removing the
read-only marks from those files that are
not supposed to be read-only.
-12-
CHAINSAW: more about
5) I use it to strip entire drives down to the
volume label in preparation for installing a
new version of DOS and a set of standard
programs as part of a procedure for
refurbishing old machines for new users.
6) We also carry it around to non-networked lab
machines to clean up students working
directories after they graduate (or
otherwise leave). A few of these machines
are networked - and we use our own copies or
the protected "public" copy instead of
carrying a floppy around.
The report generation code, on which I spent so
much time, is used only during the pre-semester cleanup
sweep. The password feature is used only for the copy that
anyone can access over the network (of course, the other
copies are either kept filed away on floppies in drawers or
are protected by our network login passwords).
I cannot say that the program is perfect or
bullet proof but, in over a year of use and testing, it has
never removed anything it wasn't told to remove. There have
been malfunctions, but they have all been benign - they
have resulted in something not being removed or the program
refusing to do anything at all; these have all been fixed.
See CHAINSAW.CPP for the version history.
One or two last notes: I thought it was
malfunctioning when it refused to remove c:\windows\fungame
from my own machine at home. I had momentarily forgotten
that a SUBST was in effect for that directory (as drive F:).
DOS refused to let CHAINSAW remove what it thought of as a
root directory. Even with the permission switch on, I got
the general ERROR message with the explanation that access
was denied. I did once get a "Protected Mode Violation"
error from Windows 3.1 (in standard mode on a PS2-30/286),
but I get those all the time). No, I will not explain why I
am trying to support Windows and Windows apps with a brain-
damaged computer. The program has not been tested under
DOS 6.0; we were smart enough to pass on that one, so I
don't have access to it.
T.E.D.
-13-
